/**
 * 
 */
package com.google.code.netz.wfe.model;

import com.google.code.netz.wfe.api.WorkflowException;

/**
 * Transaction interface is expected to be implmented by all Activity
 * implementations.
 * <p>
 * A task is a Logical Unit ofWork (LUW), and an activity is a transaction. Just
 * like a transaction, an activity should satisfy the well-known ACID
 * properties.
 * <ul>
 * <li><i><b>A</b>tomicity</i>: An activity is executed successfully (commit) or
 * is rolled back completely, i.e., a task cannot be completed partially.</li>
 * <li><i><b>C</b>onsistency</i>: The execution of an activity leads to a
 * consistent state.</li>
 * <li><i><b>I</b>solation</i>: The effect of the execution of an activity in
 * parallel with other activities is equal to the effect of the execution of one
 * activity in isolation.</i>
 * <li><i><b>D</b>urability</i>: The result of a committed activity cannot get
 * lost.</li>
 * </ul>
 * <p>
 * Type <code>T</code> is the type for the expected result.
 * 
 * @author <a href='mailto:rahul.thakur.xdev@gmail.com'>Rahul Thakur</a>
 * @since 1.0
 * @version $Id$
 */
public interface IWorkflowTransaction<T> {

	/**
	 * A {@link Transition} fires to start off a {@link IWorkflowTransaction}
	 * which wraps up all the changes to be made to state of the ICase.
	 * 
	 * @return
	 * @throws WorkflowException
	 */
	public T execute() throws WorkflowException;

	/**
	 * Rolls back the worlflow transaction in event of an error - expected or
	 * unexpected.
	 * <p>
	 * Rollback reverts the state of the workflow to the last state that the
	 * workflow was in before the {@link Transition} associated to this
	 * Transaction fired.
	 * 
	 * 
	 * @throws WorkflowException
	 */
	public void rollback() throws WorkflowException;

	/**
	 * Commits the workflow transaction when a {@link Transition} fires and
	 * completes its processing successfully.
	 * 
	 * @throws WorkflowException
	 */
	public void commit() throws WorkflowException;

}
